Copyright: Copyright © LVDI Software


Contents
  TDBImport Component  V 1.5

       Properties	Methods       Events	Technical Support  Installion  Limitations

Unit

DBImport

Description

The component TDBImport enables you to import any file in a professional way.
You can define formats using a wizard, choosing the type of file you import (variable, fixed, ...) the separator character, the fields you want, the number of records you want, and many other setttings.

The two mandatory properties are the DataSet  (the table you want to import to) and the IniFile (the file that will hold the defined formats).

Use the property ImportCaption if you want to change the default caption, the property ImportFile enables you to initialize the name of the import file, if you provide a help file set the HelpId to point to the help topic, the property ShowFormats enables you to make the button fomats visible or not, as the property ShowBrowse enables you to make the button Browse visible or not.

If you do not provide a help file you may want to make the help button not visible by setting the property ShowHelp to False.

You can change the wizard captions to suite you needs by changing the properties WizardCaption1 WizardCaption2 WizardCaption3 WizardCaption4, if you do not provide help for the wizard, just change the property ShowWizardHelp to False, else just set the property WizardHelpId to the help topic.


Properties

DataSet	ShowFormats
HelpId	ShowHelp
ImportCaption	ShowProgress
ImportFile	ShowSummary
IniFile	ShowWizardHelp
LogActivity	WizardCaption1
LogAppend	WizardCaption2
LogFile	WizardCaption3
MaxErrors	WizardCaption4
ShowBrowse	WizardHelpId
ShowErrors


Technical Support

You can contact us directly through these :

Compuserve :100733,1402

Aol 	        : lvdi

Internet        : support@lvdisoft.com

Tel	       : +33 6 07 89 26 57

Fax	       : +33 1 46 63 42 31

Address      : LVDI Software 70, rue Charles Frerot 94250 Paris-Gentilly France


DataSet
Property DataSet

Applies to

TDBImport component

Declaration

property DataSet : TDataSet;

Description

Set this property to the name of the dataset that contains the data that will receive the imported data, it should either be a TTable. The available datasets are listed in the drop down combo box for ease of use.

Example

  DBImportDialog1.DataSet := MyTable;

  DBImportDialog1.IniFile := 'IFormats.ini'

  DBImportDialog1.execute;


ImportCaption
Property ImportCaption

Applies to

TDBImport component

Declaration

property ImportCaption : string;

Default

"Import"

Description

Set this property to display a caption (window title) that suites your needs.

Example

  DBImportDialog1.ImportCaption := 'Import data to customer table';


IniFile
Property IniFile

Applies to

TDBImport component

Declaration

property DataSet : string;

Description

Set this property to the name of the IniFile that will contain the formats that the user will define using the formats wizard. You better have different inifiles for each dataset to avoid mixing things

Don't forget that you prepare a format for a known dataset, this format will contain field names, if you try to apply that format to another dataset (that have different field names) you will get the error message : 'This format is incompatible with the data base'.

You can have one inifile storing formats for different datasets but you better give good name formats, like 'CustomerFormat'.

Example

  DBImportDialog1.DataSet := MyTable;

  DBImportDialog1.IniFile := 'IFormats.ini'

  DBImportDialog1.execute;


ImportFile
Property ImportFile

Applies to

TDBImport component

Declaration

property ImportFile : string;

Default

''

Description

Set this property to initialize the edit box file name. If you don't set this property the edit box will be empty (if it's the first Import ) or will hold the last used filename.

Example

  DBImportDialog1.ImportFile := 'c:\tmp|import.txt';


HelpId
Property HelpId

Applies to

TDBImport component

Declaration

property HelpId : integer

Default

0

Description

If you provide a help file you must set this property to point to your help file topic.number.

Leave it to zero if you don't provide a help file.

Example

  DBImportDialog1.HelpId := 133;


ShowFormats
Property ShowFormats

Applies to

TDBImport component

Declaration

property ShowFormats: Boolean

Default

True

Description

This property enables you to show or hide the formats button.(that launches the formats wizard), it may be useful in some situations to force the user to choose a predefined format.

Example

  DBImportDialog1.ShowFormats := False;


ShowBrowse
Property ShowBrowse

Applies to

TDBImport component

Declaration

property ShowBrowse: Boolean

Default

True

Description

This property enables you to show or hide the browse file button..

Example

  DBImportDialog1.ShowBrowse := False;


ShowHelp
Property ShowHelp

Applies to

TDBImport component

Declaration

property ShowHelp: Boolean

Default

True

Description

This property enables you to show or hide the help button., it may be useful if you don't provide a help file or topic for the import dialog.

Example

  DBImportDialog1.ShowHelp := False;


ShowWizardHelp
Property ShowWizardHelp

Applies to

TDBImport component

Declaration

property ShowWizardHelp: Boolean

Default

True

Description

This property enables you to show or hide the formats wizard help button., it may be useful if you don't provide a help file or topic for the formats wizard dialog.

Example

  DBImportDialog1.ShowWizardHelp := False;


WizardCaption1
Property WizardCaption1

Applies to

TDBImport component

Declaration

property WizardCaption1 : string;

Default

"Formats Wizard - step 1/4"

Description

Set this property to display a caption (window title) for the formats wizard dialog (caption 1).

Example

  DBImportDialog1.WizardCaption1 := 'Formats Wizard - step 1';


WizardCaption2
Property WizardCaption2

Applies to

TDBImport component

Declaration

property WizardCaption2 : string;

Default

"Formats Wizard - step 2/4"

Description

Set this property to display a caption (window title) for the formats wizard dialog (caption 2).

Example

  DBImportDialog1.WizardCaption2 := 'Formats Wizard - step 2';


WizardCaption3
Property WizardCaption3

Applies to

TDBImport component

Declaration

property WizardCaption3 : string;

Default

"Formats Wizard - step 3/4"

Description

Set this property to display a caption (window title) for the formats wizard dialog (caption 3).

Example

  DBImportDialog1.WizardCaption3 := 'Formats Wizard - step 3';


WizardCaption4
Property WizardCaption4

Applies to

TDBImport component

Declaration

property WizardCaption4 : string;

Default

"Formats Wizard - step 4/4"

Description

Set this property to display a caption (window title) for the formats wizard dialog (caption 4).

Example

  DBImportDialog1.WizardCaption4 := 'Formats Wizard - step 4';


WizardHelpId
Property WizardHelpId

Applies to

TDBImport component

Declaration

property WizardHelpId : integer

Default

0

Description

If you provide a help file for the formats wizard dialog, you must set this property to point to your help file topic.number.

Leave it to zero if you don't provide a help file.

Example

  DBImportDialog1.HelpId := 134;


LogAppend
Property LogAppend

Applies to

TDBImport component

Declaration

property LogAppend : Boolean

Default

False

Description

If this flag is true, the text logged will be appended to any previous one instead of discarding it.
This flag can be useful when doing batch import of many files.
This flag is useful only when LogActivity is set to True.

Example

  DBImportDialog1.LogActivity := True;

  DBImportDialog1.LogFile := 'allimport.log';

  DBImportDialog1.LogAppend := True;

  DBImportDialog1.DoImport('Customers');

  DBImportDialog1.DoImport('articles');


LogActivity
Property LogActivity

Applies to

TDBImport component

Declaration

property LogActivity : Boolean

Default

False

Description

If this flag is true, the component will record in a text file the date and starting time of the import process,
the possible errors, the number of records imported, the date and time the import finished.

Example

  DBImportDialog1.LogActivity := True;

  DBImportDialog1.LogFile := 'customers.log';


Installation

Getting Started

UNZIP the archive (eg: DBIMPORT.ZIP) to a directory temporally.

Create a directory to hold this component and any others that you will install in the future. (eg: C:\DELPHI\COMPONEN) It is easier to put new components in a separate directory since you can update them easily and if there is a new release of DELPHI it will not effect your component directory.

Installation of the HLP and KWF files.

·Exit DELPHI is you are running it, as you can not install the KWF file while delphi is running.

·Move or copy help file (e.g.: DBIMPORT.HLP) to your Delphi Bin directory (suggest C:\DELPHI\BIN), it only really needs to be somewhere on the path, but the DELPHI bin directory is a good place.

·Delphi has a program to add our help index to Delphis help index. What this does is allow you to search for both delphi commands and the commands and properties of the component you want to install. This program is called HELPINST and is found in the DELPHI\HELP sub directory. Copy the keyword file (DBIMPORT.KWF) to the delphi help directory.

·Change the current directory to the Delphi Help directory (e.g.: CD C:\DELPHI\HELP)

·Run the HELPINST program and load the DELPHI.HDX file from the DELPHI\BIN directory.

·Add the .KWF file (e.g.: DBIMPORT.KWF) to the list of indexs.

·Save the new index file and then exit the HelpInst program.

Installation of the DCU, DCR, FRM, AND TXT  files.

We next must add the component to the Delphi VCL Library.Copy the DCU, DCR, FRM, and TXT files to the directory that you made for the components. (e.g.:  C:\DELPHI\COMPONEN)

Load delphi and selected the Options menu Item, and then selected the Install Components option.

·Add the directory where you have installed the components to the search path directory. All components that get installed must be in this search path.

·Click the add button and then the browse button to navigate to the directory where you copied the .DCU file (e.g.: C:\DELPHI\COMPONEN)

·Select the List Files Of Type and select Unit File *.DCU, you should then see the DCU file that you copied to the directory. Select the file DBIMPORT.DCU and clic OK, you will be returned to the Install Components dialog box.

·Click on the OK button and the VCL library will be re-built.

·You will notice on your VCL Palette bar in DELPHI that there is now a new tab called DB DIALOGS, in side here will be an icon to represent the component you just installed.


Methods

Execute
DoImport


Execute
Method Execute

Applies to

TDBImport component

Declaration

procedure execute;

Description

This method displays the import dialogue box and returns when the user click on the close button.

Example

  DBImportDialog1.DataSet := MyTable;

  DBImportDialog1.IniFile := 'IFormats.ini'

  DBImportDialog1.execute;


BeforeFieldAssign
Event BeforeFieldAssign

Applies to

TDBImport component

Declaration

property  BeforeFieldAssign: TBeforeFieldAssignEvent

TBeforeFieldAssignEvent = procedure(Sender: TObject; FieldName: string;

               FieldType : TFieldType; FieldSize : integer; var FieldValue: string) of object;

Description

This event happens before a value is assigned to the database field, it could be useful in many cases

for example perfoming a convertion before the assignement or formatting a date.

Use the FieldName, FieldType, and FieldSize informations to choose the field you want to change

and use the FieldValue to assign a new value.

Example

{In this example we import a text file that contains amounts and we need to insert a comma

Input : 50000 output : 500,00}

procedure TFrmImport.DBImportDialog1BeforeFieldAssign(Sender: TObject;

  FieldName: String; FieldType: TFieldType; var FieldValue: OpenString);

begin

if  FieldName = 'Amount'  then

Insert ( ',', FieldValue, Length(FieldValue)-1);

end;


Limitations

The following limitation applies to the 16 bits version only

The length of a text record (from the imported file) should not exceed 255 characters (the remainings will be truncated).

This limitation doesn't exist in the 32 bits version (unlimited size).

There is no limitation in the file size or number of text records (in both 16 & 32 bits)


Events

BeforeFieldAssign
BeforePost
AfterPost
OnErrorEvent


BeforePost
Event BeforePost

Applies to

TDBImport component

Declaration

property  BeforePost: TPostEvent

TPostEvent = procedure(Sender: TObject; var Cancel: boolean) of object;

Description

This event happens before a record is posted in the database, using the cancel variable we can abort the importing processs (by assigning it to True).


AfterPost
Event AfterPost

Applies to

TDBImport component

Declaration

property  AfterPost: TPostEvent

TPostEvent = procedure(Sender: TObject; var Cancel: boolean) of object;

Description

This event happens after a record is posted in the database, using the cancel variable we can abort the importing processs (by assigning it to True).


LogFile
Property LogFile

Applies to

TDBImport component

Declaration

property LogFile : string;

Default

'Import.log'

Description

Set this property to the name of the file that will used to log the import activity, this property
is useful only when LogActivity is set to True; use the property LogAppend to use this log file in append mode or not.

Example

  DBImportDialog1.DataSet := MyTable;

  DBImportDialog1.logFile := 'customers.log'

  DBImportDialog1.execute;


MaxErrors
Property MaxErrors

Applies to

TDBImport component

Declaration

property MaxErrors : integer

Default

0

Description

With this property you can specify how many errors the component will tolerate, the errors includes database errors and conversion errors; when the maximum specified is reached the import process will stop. A message will be logged if LogActivity is True, also the user will be notified if ShowErrors is set to True.

Leave it to zero if you don't want to limit the number of errors (no maximum).

Example

  DBImportDialog1.MaxErrors := 25; {reasonable!}


ShowErrors
Property ShowErrors

Applies to

TDBImport component

Declaration

property ShowErrors: Boolean

Default

True

Description

This property enables you to show or hide the errors that might occur during the import process.

This flag can be useful when doing batch import, since errors are displayed to the user as dialog boxes, if you don't set this flag to False when doing batch, the import process will be halted if an error occurs.

This flag can also be helpful if you want to provide your own error handling.

Example

  DBImportDialog1.ShowErrors := False;

  DBImportDialog1.LogActivity := True;  {non blocking error tracking}

  DBImportDialog1.MaxErrors := 25;  {it's better to limit the number of errors when doing batch}

  DBImportDialog1.DoImport ('customers');


ShowProgress
Property ShowProgress

Applies to

TDBImport component

Declaration

property ShowProgress: Boolean

Default

True

Description

This property enables you to show or hide the progress bar, this can be useful when doing batch processing (no user interaction), and also to speedup the import process.

Example

  DBImportDialog1.ShowProgress := False;


ShowSummary
Property ShowSummary

Applies to

TDBImport component

Declaration

property ShowSummary: Boolean

Default

True

Description

When this property is set to True, at the end of the import the component will display how many records were imported and how many errors occured.
Set this property to False when doing batch imports to avoid blocking the process.

Example

  DBImportDialog1.ShowSummary := False;


OnErrorEvent
Event OnErrorEvent

Applies to

TDBImport component

Declaration

property  ErrorEvent : TErrorEvent;

TErrorEvent = procedure(Sender: TObject; ErrorMsg,FieldName,FieldValue: string; var Cancel: boolean) of object;

Description

This event happens when an error (exception) occurs, by using this event you can control the flow and customize the error handling; using the cancel variable you can abort the importing processs (by assigning it to True).
The parameters passed to the handler are:
ErrorMsg : The error message sent with the exception
FieldName: The field that was processed when the error occured.
FieldValue: The valued to be assigned to the field when the error occured.


DoImport
Method DoImport

Applies to

TDBImport component

Declaration

procedure DoImport(format: string);

Description

This method allows to do importing in batch mode, without user interface.

A previously prepared format should be used.
The flags ShowErrors and ShowSummary must set to False to avoid any blocking dialog,

the flag ShowProgress can be True since it's non-blocking, but it slows down the process a little bit.

Example

  DBImportDialog1.IniFile := 'IFormats.ini'

  DBImportDialog1.ShowErrors := False; {set these flags to False to prevent displays of dialogs}

  DBImportDialog1.ShowSummary := False;

  DBImportDialog1.IniFile := 'IFormats.ini'

  DBImportDialog1.LogActivity := True; {Track importing in a file}

  DBImportDialog1.LogAppend := True; {Useful when importing many files successively}

  DBImportDialog1.DataSet := CustomersTable;

  DBImportDialog1.DoImport ('Customers');

  DBImportDialog1.DataSet := OrdersTable;

  DBImportDialog1.DoImport ('Orders');